home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbretdata.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.7 KB  |  99 lines
  1. .Na "dbretdata" 
  2. .mc |
  3. .Aa
  4. .Fu
  5. Return a pointer to a return parameter value generated by a stored procedure.
  6. .Ih "stored procedure, return parameters"
  7. .Ih "return parameters from stored procedures"
  8. .Sy
  9. .Sf "BYTE *dbretdata(dbproc, retnum)"
  10. .Sp "DBPROCESS" "*dbproc"
  11. .Sp "int" "retnum"
  12. .Co
  13. .Bl
  14. \f2dbretdata()\f1 returns a pointer to a return parameter value generated by a stored procedure.
  15. It is useful in conjunction with remote procedure calls and EXECUTE statements on stored procedures.
  16. .Bl
  17. \*N stored procedures can return values for specified ``return parameters.''
  18. Changes made to the value of a return parameter inside the stored procedure
  19. are then available to the program that called the procedure.
  20. This is analogous to the ``pass by reference'' facility available in some
  21. programming languages.
  22. .sp 0.5v
  23. For a parameter to function as a return parameter,
  24. it must be declared as such within the stored procedure.
  25. The EXECUTE statement or remote procedure call 
  26. that calls the stored procedure must also indicate that the parameter should function
  27. as a return parameter.
  28. In the case of a remote procedure call, it is the \f2dbrpcparam()\f1 routine that specifies whether
  29. a parameter is a return parameter.
  30. .Bl
  31. When executing a stored procedure,
  32. the server returns any parameter values immediately after returning all other results.
  33. Therefore, the application can call \f2dbretdata()\f1 only after 
  34. processing the stored procedure's results by calling 
  35. \f2dbresults()\f1, as well as \f2dbnextrow()\f1 if appropriate.
  36. (Note that a stored procedure can generate several sets of results\(emone for each SELECT
  37. it contains.
  38. Before the application can call \f2dbretdata()\f1 or any other routines that
  39. process return parameters, it
  40. must call \f2dbresults()\f1 and \f2dbnextrow()\f1 as many times as necessary
  41. to process all the results.)
  42. .Bl
  43. If the stored procedure is invoked with a remote procedure call,
  44. the return parameter values are automatically available to the application.
  45. If, on the other hand,
  46. the stored procedure is invoked with an EXECUTE statement, 
  47. the return parameter values are available only if the command batch 
  48. containing the EXECUTE statement uses
  49. local variables, not constants, for the return parameters.
  50. .Bl
  51. Other routines return additional information about return parameter values:
  52. .in +3n
  53. .Bl *
  54. \f2dbnumrets()\f1 returns the total number of return parameter values.
  55. .Bl *
  56. \f2dbretlen()\f1 returns the length of a parameter value.
  57. .Bl *
  58. \f2dbretname()\f1 returns the name of a parameter value.
  59. .Bl *
  60. \f2dbrettype()\f1 returns the datatype of a parameter value.
  61. .in -3n
  62. .Bl
  63. For an example of this routine,
  64. see Example 8 in the \f2\*L Reference Supplement\f1.
  65. .Bz
  66. .Pa
  67. .Pi dbproc
  68. A pointer to the DBPROCESS structure that provides the connection
  69. for a particular front-end/\*S process.  It contains all the
  70. information that \*L uses to manage communications and data between the
  71. front end and \*S.
  72. .Pi retnum
  73. The number of the return parameter value of interest.
  74. The first return value is 1.
  75. Values are returned in the same order as the parameters were originally specified in the stored procedure's 
  76. CREATE PROCEDURE statement.
  77. (Note that this is not necessarily the same order as specified in the remote procedure call.)
  78. When specifying \f2retnum\f1, non-return parameters do not count.
  79. For example, if the second parameter in a stored procedure is the only return parameter, its \f2retnum\f1 is
  80. 1, not 2.
  81. .in -.375i
  82. .Re
  83. .br
  84. A pointer to the specified return value.
  85. If \f2retnum\f1 is out of range, \f2dbretdata()\f1 returns NULL.
  86. To determine whether the data really has a null value
  87. (and \f2retnum\f1 is not merely out of range),
  88. check for a return of 0 from \f2dbretlen()\f1.
  89. .Sa
  90. dbnextrow,
  91. dbnumrets, 
  92. dbresults,
  93. dbretlen, 
  94. dbretname,
  95. dbrettype,
  96. dbrpcinit,
  97. dbrpcparam
  98. .mc
  99.